<html>
<head>
<link href="../../style/style.css" rel="stylesheet" type="text/css">
</head>
<body>
<p class="heading">
Gl_Window Object (part of the WidgetManager module)
</p>
<p class="subheading">
Description:
</p>
<p>
The Gl_Window is a draggable, resizable, scrolling container that can be used to display external content much like a normal
web browser window. These objects are fully re-skinnable, which means all the graphic elements can be replaced to change the
look of the windows. Buttons on the titlebar can be changed around or not used at all, depending upon the author's choices.
Gl_Windows can also have menubars and statusbars added to them very easily, to further enhance their usefulness! The Gl_Window
objects are usually accessed via the WidgetManager. They should <span class="strong">never</span> be created or destroyed directly as it could cause
problems if the WidgetManager loses track of what's happening.
</p>

<p class="subheading">
To use:
</p>

<p class="jcode">
&lt;script language="Javascript" src="gamelib_widgets.js"&gt;&lt;/script&gt;
</p>

<p>
An example of creating a new Gl_Window is given in the <a href="../widgetdoc.html">Widget docs</a>. This document
will describe the useful methods and properties of Gl_Windows. In practice you're unlikely to need to call many of the
methods directly unless your scripts have very special requirements...
</p>

<p class="subheading">
List of methods for Gl_Windows
</p>

<p>
<a href="#addMenuBar">addMenuBar</a><br />
<a href="#addStatusBar">addStatusBar</a><br />
<a href="#addVScrollBar">addVScrollBar</a><br />
<a href="#changeContent">changeContent</a><br />
<a href="#childDead">childDead</a><br />
<a href="#destroy">destroy</a><br />
<a href="#dragMoveTo">dragMoveTo</a><br />
<a href="#dragResizeTo">dragResizeTo</a><br />
<a href="#load">load</a><br />
<a href="#maximize">maximize</a><br />
<a href="#moveNoClipTo">moveNoClipTo</a><br />
<a href="#moveTo">moveTo</a><br />
<a href="#moveToTop">moveToTop</a><br />
<a href="#positionElements">positionElements</a><br />
<a href="#resizeTo">resizeTo</a><br />
<a href="#removeVScrollBar">removeVScrollBar</a><br />
<a href="#scroll">scroll</a><br />
<a href="#search">search</a><br />
<a href="#setActive">setActive</a><br />
<a href="#setBGColour">setBGColour</a><br />
<a href="#setStatus">setStatus</a><br />
<a href="#setTitle">setTitle</a><br />
<a href="#shade">shade</a><br />
<a href="#switchToOutlines">switchToOutlines</a><br />
<a href="#switchToOpaque">switchToOpaque</a><br />
<a href="#unMaximize">unMaximize</a><br />
</p>

<p class="subheading">
List of (useful) properties for Gl_Windows
</p>

<p>
<a href="#hasMenuBar">hasMenuBar</a><br />
<a href="#hasStatusBar">hasStatusBar</a><br />
<a href="#height">height</a><br />
<a href="#index">index</a><br />
<a href="#maximized">maximized</a><br />
<a href="#scrollBarWidth">scrollBarWidth</a><br />
<a href="#scrollX">scrollX</a><br />
<a href="#scrollY">scrollY</a><br />
<a href="#searchMatches">searchMatches</a><br />
<a href="#shaded">shaded</a><br />
<a href="#statusTxt">statusTxt</a><br />
<a href="#title">title</a><br />
<a href="#URL">URL</a><br />
<a href="#width">width</a><br />
<a href="#x">x</a><br />
<a href="#y">y</a><br />
<a href="#z">z</a><br />
</p>


<p class="subheading">
Descriptions of methods for Gl_Windows
</p>

<table>
<tr>
<th>Method</th><th NOWRAP>Parameters</th><th>Description</th>
</tr>

<tr>
<a name="addMenuBar"></a>
<td>addMenuBar</td>
<td>MenuBar Object</td>
<td>
When passed a menubar object as the sole parameter, the menubar will be fixed to the top of the window, and resize with its
new parent window. See the <a href="gl_menubardoc.html">menuBar docs</a> for more details of the menuBar object.
</td>
</tr>

<tr>
<a name="addStatusBar"></a>
<td>addStatusBar</td>
<td>String</td>
<td>
This method adds a statusBar to a window. There's no need to create the statusBar yourself. The sole (optional) parameter is the text
to display in the status bar.
</td>
</tr>

<tr>
<a name="addVScrollBar"></a>
<td>addVScrollBar</td>
<td>none</td>
<td>
Private method - do not use.
</td>
</tr>

<tr>
<a name="changeContent"></a>
<td>changeContent</td>
<td>String</td>
<td>
This method is used to re-write the window with new HTML content. The window will be remeasured after this, and scrollbars
hidden/shown to suit.
</td>
</tr>

<tr>
<a name="childDead"></a>
<td>childDead</td>
<td>none</td>
<td>
Private method - do not use.
</td>
</tr>

<tr>
<a name="destroy"></a>
<td>destroy</td>
<td>none</td>
<td>
Private method - do not use.
</td>
</tr>

<tr>
<a name="dragMoveTo"></a>
<td>dragMoveTo</td>
<td>none</td>
<td>
Private method - do not use.
</td>
</tr>

<tr>
<a name="dragResizeTo"></a>
<td>dragResizeTo</td>
<td>none</td>
<td>
Private method - do not use.
</td>
</tr>

<tr>
<a name="load"></a>
<td>load</td>
<td>String</td>
<td>
This is used to load a new page into a window. The WidgetManager actually handles this, via its internal loading stack. This
means a script can start several windows loading, and the WidgetManager will handle the synchronisation, loading the windows
in the correct order. The HTML is parsed after loading, so that links and forms will not screw up the widgetManager, or any
other GUI elements. If the following string is found in the body of the page: <span class="strong">
&lt!-- EXTERNAL_LINKS --&gt;</span>, then all links in the page
will load into new windows. Otherwise they will replace the interface (possibly not what you'd want to happen).
</td>
</tr>

<tr>
<a name="maximize"></a>
<td>maximize</td>
<td>none</td>
<td>
Causes the window to grow to fill the browser window. In this state, the window cannot be dragged or resized until its
<a href="#unMaximize">unMaximize</a> method is called and it returns to its normal size.
</td>
</tr>

<tr>
<a name="moveNoClipTo"></a>
<td>moveNoClipTo</td>
<td>Numeric, Numeric</td>
<td>
The two parameters passed are the new X and Y coordinates for the top left hand corner of the window. This method is really
designed for internal use, as it allows the window to be moved completely out of the browser window.
</td>
</tr>

<tr>
<a name="moveTo"></a>
<td>moveTo</td>
<td>Numeric, Numeric</td>
<td>
The two parameters passed are the new X and Y coordinates for the top left hand corner of the window. Windows cannot be moved
off of the browser page using this method.
</td>
</tr>

<tr>
<a name="moveToTop"></a>
<td>moveToTop</td>
<td>none</td>
<td>
This will move the window to the top of the Z-stack of windows. This means that this window will appear above all other
windows on the screen.
</td>
</tr>

<tr>
<a name="positionElements"></a>
<td>positionElements</td>
<td>none</td>
<td>
This causes the window to check and reset the scrollbar, width, height and any elements contained within it. If you
wish to manually change the scrolled position of the window by changing the <a href="#scrollX">scrollX</a> and
<a href="#scrollY">scrollY</a> properties, you must call this method afterwards to update the window.
</td>
</tr>

<tr>
<a name="resizeTo"></a>
<td>resizeTo</td>
<td>Numeric, Numeric</td>
<td>
Causes the window to resize to X,Y. A window cannot be resized larger than the browser window in either axis.
</td>
</tr>

<tr>
<a name="removeVScrollBar"></a>
<td>removeVScrollBar</td>
<td>none</td>
<td>
Private method - do not use.
</td>
</tr>

<tr>
<a name="scroll"></a>
<td>scroll</td>
<td>Numeric, Numeric</td>
<td>
Private method - do not use.
</td>
</tr>

<tr>
<a name="search"></a>
<td>search</td>
<td>String</td>
<td>
This causes the window to search its loaded or written contents for matches for the String passed as the parameter.
Any text matches are highlighted in the window, and the statusBar (if present) will display the number of matches.
</td>
</tr>

<tr>
<a name="setActive"></a>
<td>setActive</td>
<td>none</td>
<td>
Makes this window the active window. This also causes the window to move to the top of the Z-stacking order.
</td>
</tr>

<tr>
<a name="setBGColour"></a>
<td>setBGColour</td>
<td>String</td>
<td>
Sets the background colour for the window. String passed must be a colour value.
</td>
</tr>

<tr>
<a name="setStatus"></a>
<td>setStatus</td>
<td>String</td>
<td>
Sets the text in the status bar (if present).
</td>
</tr>

<tr>
<a name="setTitle"></a>
<td>setTitle</td>
<td>String</td>
<td>
Sets the text in the title bar.
</td>
</tr>

<tr>
<a name="shade"></a>
<td>shade</td>
<td>none</td>
<td>
Causes the window to switch between "shaded" and "unshaded" states. When shaded, the main body of the window is hidden,
so only the title bar is visible. The window can still be dragged around, maximized or destroyed in this state.
</td>
</tr>

<tr>
<a name="switchToOutlines"></a>
<td>switchToOutlines</td>
<td>none</td>
<td>
Private method - do not use.
</td>
</tr>

<tr>
<a name="switchToOpaque"></a>
<td>switchToOpaque</td>
<td>none</td>
<td>
Private method - do not use.
</td>
</tr>

<tr>
<a name="unMaximize"></a>
<td>unMaximize</td>
<td>none</td>
<td>
Switches window from maximized state back to normal.
</td>
</tr>

</table>


<p class="subheading">
Descriptions of (useful) properties for Gl_Windows
</p>

<table>
<tr>
<th>Property</th><th NOWRAP>Data Type</th><th NOWRAP>Read/Write</th><th>Description</th>
</tr>

<tr>
<a name="hasMenuBar"></a>
<td>hasMenuBar</td>
<td>Boolean</td>
<td>R</td>
<td>
True if this window has a menuBar attached to it. See the <a href="menubar.html">menuBar docs</a>
for more details of the menuBar object.
</td>
</tr>

<tr>
<a name="hasStatusBar"></a>
<td>hasStatusBar</td>
<td>Boolean</td>
<td>R</td>
<td>
True if this window has a statusBar object attached to it. See the <a href="statusbar.html">statusBar docs</a>
for more details of the statusBar object.
</td>
</tr>

<tr>
<a name="height"></a>
<td>height</td>
<td>Numeric</td>
<td>R</td>
<td>
The total height including titlebar and statusbar (if attached) of the window.
</td>
</tr>

<tr>
<a name="index"></a>
<td>index</td>
<td>Numeric</td>
<td>R</td>
<td>
The window's unique index. This is its position in the widgetManager's .windows[] array.
</td>
</tr>

<tr>
<a name="maximized"></a>
<td>maximized</td>
<td>Boolean</td>
<td>R</td>
<td>
True if the window has been maximized.
</td>
</tr>

<tr>
<a name="scrollBarWidth"></a>
<td>scrollBarWidth</td>
<td>Numeric</td>
<td>R</td>
<td>
If this is anything other than zero, the window is displaying a scrollbar. This would be due to the content of the window
being longer than the window's current canvasHeight (the window's height-(titlebar height+statusbar height+menubar height).
</td>
</tr>

<tr>
<a name="scrollX"></a>
<td>scrollX</td>
<td>Numeric</td>
<td>R/W</td>
<td>
The window contents scrolled position in the X axis. If you set this value the window will not be updated unless you also
call its <a href="#positionElements">positionElements</a> method.
</td>
</tr>

<tr>
<a name="scrollY"></a>
<td>scrollY</td>
<td>Numeric</td>
<td>R/W</td>
<td>
The window contents scrolled position in the Y axis. If you set this value the window will not be updated unless you also
call its <a href="#positionElements">positionElements</a> method.
</td>
</tr>

<tr>
<a name="searchMatches"></a>
<td>searchMatches</td>
<td>Numeric</td>
<td>R</td>
<td>
This is set after the <a href="#search">search</a> method has been called on the window. It reports the number of matches found within the
window's current contents.
</td>
</tr>

<tr>
<a name="shaded"></a>
<td>shaded</td>
<td>Boolean</td>
<td>R</td>
<td>
True if the window is currently shaded (minimized).
</td>
</tr>

<tr>
<a name="statusTxt"></a>
<td>statusTxt</td>
<td>String</td>
<td>R</td>
<td>
The text currently displayed in the status bar attached to the window. Use the <a href="#setStatus">setStatus</a> method to change this text.
</td>
</tr>

<tr>
<a name="title"></a>
<td>title</td>
<td>String</td>
<td>R</td>
<td>
The text currently displayed in the title bar. Use the <a href="#setTitle">setTitle</a> method to change this text.
</td>
</tr>

<tr>
<a name="width"></a>
<td>width</td>
<td>Numeric</td>
<td>R</td>
<td>
The current width of the window.
</td>
</tr>

<tr>
<a name="x"></a>
<td>x</td>
<td>Numeric</td>
<td>R</td>
<td>
The current X position of the window. This is the position of the left-hand edge of the window relative to the left-hand edge
of the browser window.
</td>
</tr>

<tr>
<a name="y"></a>
<td>y</td>
<td>Numeric</td>
<td>R</td>
<td>
The current Y position of the window. This is the position of the top edge of the window relative to the top edge
of the browser window.
</td>
</tr>

<tr>
<a name="z"></a>
<td>z</td>
<td>Numeric</td>
<td>R</td>
<td>
The current Z index of the window. Windows with higher Z indexes move over those with lower Z indexes. To move a window
to the top of the stack on the desktop, use the <a href="#setActive">setActive</a> method.
</td>
</tr>

</table>

</body>
</html>